TODO

A modern Python client for NordVPN with automatic API fallback support, providing both a CLI interface and a Python library.

# Install system requirements first
brew install openvpn  # macOS
sudo apt install openvpn  # Ubuntu/Debian
sudo dnf install openvpn  # Fedora/RHEL

# Then install and use the package
pip install nyord-vpn
export NORD_USER="username" NORD_PASSWORD="password"
nyord-vpn go de  # Connect to a German VPN
nyord-vpn info  # Check status
nyord-vpn bye  # Disconnect

DEVELOPMENT

After each set of changes, update @TODO.md with what you’ve done (). Upgrade priorities for NEXT TODO (- [!]), re-think the normal TODO ()

Periodically do:

uv venv; source .venv/bin/activate; uv pip install -e .[dev,test]; tree -I *cache__; hatch fmt --unsafe-fixes; hatch fmt --unsafe-fixes; hatch -e test run test;

and react to the results. Use uv pip... instead of pip... if needed.

Working modality

You’ll lead two experts: “Ideot” for creative, unorthodox ideas and “Critin” to critique flawed thinking and moderate for balanced discussions. The three of you shall illuminate knowledge with concise, beautiful responses, process methodically for clear answers, collaborate step-by-step, sharing thoughts and adapting. If errors are found, step back and focus on accuracy and progress.

Independently tackle challenges systematically, being adaptable and resourceful. Research deeply using all tools, revising to ensure conclusive, exhaustive, insightful results. When you’re finished, print “Wait, but” to go back, think & reflect, revise & improvement what you’ve done (but don’t invent functionality freely). Repeat this. Focus on minimal viable next versions of the code. Ship often and early.

General coding principles

Verify info. No assumptions. No apologies. No major invented changes. No unneeded confirmations or checks. Keep existing code and structures unless they need to change. No unnecessary updates or current implementation discussion. Avoid magic numbers, handle edge cases, use assertions to validate assumptions and catch potential errors early.

Every code can fail. Write code that fails gracefully and is UX friendly: uses retries (within reason), does not make stupid assumptions, tests successes, uses fallbacks and backoffs, and then, if the code needs to message the user, be clear and suggest to the user the next steps. Don’t prompt the user to do something that the computer can obviously do. The code should ask the user only if there is a real decision to be made. And you should ask me only if a real decision is needed.

Keep track of paths

In every source file you create or edit, always maintain the up-to-date this_file record that shows the path of the current file relative to the root of the project. Place the this_file record near the top of the file, as a comment after the shebangs, or in the YAML Markdown frontmatter. Use these records for orientation.

Follow this style for Python

Follow PEP 8. Write clear names. Keep it simple (PEP 20). Use type hints, imperative docstrings (PEP 257), f-strings, and structural pattern matching. Extract repeated logic. Handle errors. Keep functions small. Prefer flat structures. Use pathlib, pydantic as needed. Write maintainable code.

EVEN IF YOU’RE NOT prompted, always write a “verbose” mode logugu-based logging for debug purposes, write explanatory docstrings and comments that not only explain what a given item (module, function, method) does, but also why it does it, and where and how it’s used elsewhere in the code.

ONLY IF YOU ARE prompted, extend existing features in a way that adds complexity, or refactor in a way that may break things. Remember: minimal viable next version is always our goal. IF NOT PROMPTED, do NOT make such changes.

For CLI Python scripts, use fire & rich, and start the script with

#!/usr/bin/env -S uv run -s
# /// script
# dependencies = ["PKG1", "PKG2"]
# ///
# this_file: PATH_TO_CURRENT_FILE

Nyord VPN Codebase Refactoring Specification

Completed Tasks

Remaining Tasks

API Module (src/nyord_vpn/api/)

src/nyord_vpn/api/api.py

Action: Modify to make this the central API interface.

src/nyord_vpn/api/v1_*.py files

Action: Keep but mark as deprecated and clean up.

src/nyord_vpn/api/v2_servers.py

Action: Refine and improve.

Core Module (src/nyord_vpn/core/)

src/nyord_vpn/core/api.py and src/nyord_vpn/core/base.py

Action: Deprecate and eventually remove.

src/nyord_vpn/core/client.py

Action: Refactor significantly to use the new API.

Network Module (src/nyord_vpn/network/)

src/nyord_vpn/network/server.py

Action: Refactor to use new API.

src/nyord_vpn/network/vpn.py

Action: Refactor for better maintainability.

src/nyord_vpn/network/vpn_commands.py

Action: Refactor for better usability.

Utils Module (src/nyord_vpn/utils/)

src/nyord_vpn/utils/templates.py

Action: Simplify with tenacity.

Main Module Files

src/nyord_vpn/__main__.py

Action: Update to use new API.

Tests

Action: Update to reflect code changes.

Documentation

Action: Update documentation.